home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / exec31.arc / EXEC.H < prev    next >
Encoding:
C/C++ Source or Header  |  1991-08-25  |  10.9 KB  |  260 lines
  1. /*
  2.     --- Version 3.1 91-08-17 23:05 ---
  3.  
  4.    EXEC.H: EXEC function with memory swap - Main function header file.
  5.  
  6.    Public domain software by
  7.  
  8.         Thomas Wagner
  9.         Ferrari electronic GmbH
  10.         Beusselstrasse 27
  11.         D-1000 Berlin 21
  12.         Germany
  13. */
  14.  
  15.  
  16. extern int do_exec (char *xfn, char *pars, int spawn, unsigned needed,
  17.                           char **envp);
  18.  
  19. /*>e
  20.    The EXEC function.
  21.  
  22.       Parameters:
  23.  
  24.          xfn      is a string containing the name of the file
  25.                   to be executed. If the string is empty,
  26.                   the COMSPEC environment variable is used to
  27.                   load a copy of COMMAND.COM or its equivalent.
  28.                   If the filename does not include a path, the
  29.                   current PATH is searched after the default.
  30.                   If the filename does not include an extension,
  31.                   the path is scanned for a COM, EXE, or BAT file 
  32.                   in that order.
  33.  
  34.          pars     The program parameters.
  35.  
  36.          spawn    If 0, the function will terminate after the 
  37.                   EXECed program returns, the function will not return.
  38.  
  39.                   NOTE: If the program file is not found, the function 
  40.                         will always return with the appropriate error 
  41.                         code, even if 'spawn' is 0.
  42.  
  43.                   If non-0, the function will return after executing the
  44.                   program. If necessary (see the "needed" parameter),
  45.                   memory will be swapped out before executing the program.
  46.                   For swapping, spawn must contain a combination of the 
  47.                   following flags:
  48.  
  49.                      USE_EMS  (0x01)  - allow EMS swap
  50.                      USE_XMS  (0x02)  - allow XMS swap
  51.                      USE_FILE (0x04)  - allow File swap
  52.  
  53.                   The order of trying the different swap methods can be
  54.                   controlled with one of the flags
  55.  
  56.                      EMS_FIRST (0x00) - EMS, XMS, File (default)
  57.                      XMS_FIRST (0x10) - XMS, EMS, File
  58.  
  59.                   If swapping is to File, the attribute of the swap file
  60.                   can be set to "hidden", so users are not irritated by
  61.                   strange files appearing out of nowhere with the flag
  62.  
  63.                      HIDE_FILE (0x40)    - create swap file as hidden
  64.  
  65.                   and the behaviour on Network drives can be changed with
  66.  
  67.                      NO_PREALLOC (0x100) - don't preallocate
  68.                      CHECK_NET (0x200)   - don't preallocate if file on net.
  69.  
  70.                   This checking for Network is mainly to compensate for
  71.                   a strange slowdown on Novell networks when preallocating
  72.                   a file. You can either set NO_PREALLOC to avoid allocation
  73.                   in any case, or let the prep_swap routine decide whether
  74.                   to do preallocation or not depending on the file being
  75.                   on a network drive (this will only work with DOS 3.1 or 
  76.                   later).
  77.  
  78.          needed   The memory needed for the program in paragraphs (16 Bytes).
  79.                   If not enough memory is free, the program will 
  80.                   be swapped out. 
  81.                   Use 0 to never swap, 0xffff to always swap. 
  82.                   If 'spawn' is 0, this parameter is irrelevant.
  83.  
  84.          envp     The environment to be passed to the spawned
  85.                   program. If this parameter is NULL, a copy
  86.                   of the parent's environment is used (i.e.
  87.                   'putenv' calls have no effect). If non-NULL,
  88.                   envp must point to an array of pointers to
  89.                   strings, terminated by a NULL pointer (the
  90.                   standard variable 'environ' may be used).
  91.  
  92.       Return value:
  93.  
  94.          0x0000..00FF: The EXECed Program's return code
  95.  
  96.          0x0101:       Error preparing for swap: no space for swapping
  97.          0x0102:       Error preparing for swap: program too low in memory
  98.  
  99.          0x0200:       Program file not found
  100.          0x0201:       Program file: Invalid drive
  101.          0x0202:       Program file: Invalid path
  102.          0x0203:       Program file: Invalid name
  103.          0x0204:       Program file: Invalid drive letter
  104.          0x0205:       Program file: Path too long
  105.          0x0206:       Program file: Drive not ready
  106.          0x0207:       Batchfile/COMMAND: COMMAND.COM not found
  107.          0x0208:       Error allocating temporary buffer
  108.  
  109.          0x03xx:       DOS-error-code xx calling EXEC
  110.  
  111.          0x0400:       Error allocating environment buffer
  112.  
  113.          0x0500:       Swapping requested, but prep_swap has not 
  114.                        been called or returned an error.
  115.          0x0501:       MCBs don't match expected setup
  116.          0x0502:       Error while swapping out
  117.  
  118.          0x0600:       Redirection syntax error
  119.          0x06xx:       DOS error xx on redirection
  120. <*/
  121.  
  122. /*>d
  123.    Die EXEC Funktion.
  124.  
  125.       Parameter:
  126.  
  127.          xfn      ist ein String mit dem Namen der auszuführenden Datei.
  128.                   Ist der String leer, wird die COMSPEC Umgebungsvariable
  129.                   benutzt um COMMAND.COM oder das Equivalent zu laden.
  130.                   Ist kein Pfad angegeben, wird nach dem aktuellen Pfad
  131.                   der in der PATH Umgebungsvariablen angegebene Pfad
  132.                   durchsucht.
  133.                   Ist kein Dateityp angegeben, wird der Pfad nach
  134.                   einer COM oder EXE Datei (in dieser Reihenfolge) abgesucht.
  135.  
  136.          pars     Die Kommandozeile
  137.  
  138.          spawn    Wenn 0, wird der Programmlauf beendet wenn das
  139.                   aufgerufene Programm zurückkehrt, die Funktion kehrt
  140.                   nicht zurück.
  141.  
  142.                   HINWEIS: Wenn die auszuführende Datei nicht gefunden
  143.                         wird, kehrt die Funktion mit einem Fehlercode
  144.                         zurück, auch wenn der 'spawn' Parameter 0 ist.
  145.  
  146.                   Wenn nicht 0, kehrt die Funktion nach Ausführung des
  147.                   Programms zurück. Falls notwendig (siehe den Parameter
  148.                   "needed") wird der Programmspeicherbereich vor Aufruf 
  149.                   ausgelagert.
  150.                   Zur Auslagerung muß der Parameter eine Kombination der
  151.                   folgenden Flags enthalten:
  152.  
  153.                      USE_EMS  (0x01)  - Auslagerung auf EMS zulassen
  154.                      USE_XMS  (0x02)  - Auslagerung auf XMS zulassen
  155.                      USE_FILE (0x04)  - Auslagerung auf Datei zulassen
  156.  
  157.                   Die Reihenfolge der Versuche, auf die verschiedenen
  158.                   Medien auszulagern kann mit einem der folgenden
  159.                   Flags beeinflußt werden:
  160.  
  161.                      EMS_FIRST (0x00) - EMS, XMS, Datei (Standard)
  162.                      XMS_FIRST (0x10) - XMS, EMS, Datei
  163.  
  164.                   Wenn die Auslagerung auf Datei erfolgt, kann das
  165.                   Attribut dieser Datei auf "hidden" gesetzt werden,
  166.                   damit der Benutzer nicht durch unversehends auftauchende
  167.                   Dateien verwirrt wird:
  168.  
  169.                      HIDE_FILE (0x40) - Auslagerungsdatei "hidden" erzeugen
  170.  
  171.                   Außerdem kann das Verhalten auf Netzwerk-Laufwerken 
  172.                   beeinflußt werden mit
  173.  
  174.                      NO_PREALLOC (0x100) - nicht Präallozieren
  175.                      CHECK_NET (0x200)   - nicht Präallozieren wenn Netz.
  176.  
  177.                   Diese Prüfung auf Netzwerk ist hauptsächlich sinnvoll
  178.                   für Novell Netze, bei denen eine Präallozierung eine
  179.                   erhebliche Verzögerung bewirkt. Sie können entweder mit
  180.                   NO_PREALLOC eine Präallozierung in jedem Fall ausschließen,
  181.                   oder die Entscheidung mit CHECK_NET prep_swap überlassen.
  182.                   In diesem Fall wird nicht präalloziert wenn die Datei
  183.                   auf einem Netzwerk-Laufwerk liegt (funktioniert nur
  184.                   mit DOS Version 3.1 und späteren).
  185.  
  186.          needed   Der zur Ausführung des Programms benötigte Speicher
  187.                   in Paragraphen (16 Bytes). Wenn nicht ausreichend 
  188.                   freier Speicher vorhanden ist, wird der Programm-
  189.                   speicherbereich ausgelagert.
  190.                   Bei Angabe von 0 wird nie ausgelagert, bei Angabe
  191.                   von 0xffff wird immer ausgelagert.
  192.                   Ist der Parameter 'spawn' 0, hat 'needed' keine Bedeutung.
  193.  
  194.          envp     Die dem gerufenen Programm zu übergebenden 
  195.                   Umgebungsvariablen. Ist der Parameter NULL,
  196.                   wird eine Kopie der Vater-Umgebung benutzt,
  197.                   d.h. daß Aufrufe von "putenv" keinen Effekt haben.
  198.                   Wenn nicht NULL muß envp auf ein Array von Zeigern
  199.                   auf Strings zeigen, das durch einen NULL Zeiger
  200.                   abgeschlossen wird. Hierfür kann die Standardvariable 
  201.                   "environ" benutzt werden.
  202.  
  203.       Liefert:
  204.  
  205.          0x0000..00FF: Rückgabewert des aufgerufenen Programms
  206.  
  207.          0x0101:       Fehler bei Vorbereitung zum Auslagern
  208.                         kein Speicherplatz in XMS/EMS/Datei
  209.          0x0102:       Fehler bei Vorbereitung zum Auslagern
  210.                         der Programmcode ist zu nah am Beginn des
  211.                         Programms.
  212.  
  213.          0x0200:       Auszuführende Programmdatei nicht gefunden
  214.          0x0201:       Programmdatei: Ungültiges Laufwerk
  215.          0x0202:       Programmdatei: Ungültiger Pfad
  216.          0x0203:       Programmdatei: Ungültiger Dateiname
  217.          0x0204:       Programmdatei: Ungültiger Laufwerksbuchstabe
  218.          0x0205:       Programmdatei: Pfad zu lang
  219.          0x0206:       Programmdatei: Laufwerk nicht bereit
  220.          0x0207:       Batchfile/COMMAND: COMMAND.COM nicht gefunden
  221.          0x0208:       Fehler beim allozieren eines temporären Puffers
  222.  
  223.          0x03xx:       DOS-Fehler-Code xx bei Aufruf von EXEC
  224.  
  225.          0x0400:       Fehler beim allozieren der Umgebungsvariablenkopie
  226.  
  227.          0x0500:       Auslagerung angefordert, aber prep_swap wurde nicht
  228.                        aufgerufen oder lieferte einen Fehler
  229.          0x0501:       MCBs entsprechen nicht dem erwarteten Aufbau
  230.          0x0502:       Fehler beim Auslagern
  231.  
  232.          0x0600:       Redirection Syntaxfehler
  233.          0x06xx:       DOS-Fehler xx bei Redirection
  234. <*/
  235.  
  236. /*e Return codes (only upper byte significant) */
  237. /*d Fehlercodes (nur das obere Byte signifikant) */
  238.  
  239. #define RC_PREPERR   0x0100
  240. #define RC_NOFILE    0x0200
  241. #define RC_EXECERR   0x0300
  242. #define RC_ENVERR    0x0400
  243. #define RC_SWAPERR   0x0500
  244. #define RC_REDIRERR  0x0600
  245.  
  246. /*e Swap method and option flags */
  247. /*d Auslagerungsmethoden ond Optionen */
  248.  
  249. #define USE_EMS      0x01
  250. #define USE_XMS      0x02
  251. #define USE_FILE     0x04
  252. #define EMS_FIRST    0x00
  253. #define XMS_FIRST    0x10
  254. #define HIDE_FILE    0x40
  255. #define NO_PREALLOC  0x100
  256. #define CHECK_NET    0x200
  257.  
  258. #define USE_ALL      (USE_EMS | USE_XMS | USE_FILE)
  259.  
  260.